PF.TXT                  THE FF USERS MANUAL



                         Table of contents


         Overview   FF, What is it all about _________________   2

         1.         Getting Started __________________________   2

         2.         Sequential File Forth: An Overview ________  6

         3.         What is the same as F83? __________________  8

         4.         What is different from F83? _______________  9

         5.         Differences from PF, ZF & DF ______________ 10

         6.         SED: The Editor ___________________________ 11

         7.         The Debugger, and the Tools Available _____ 19

         8.         DOS: The interface ________________________ 25

         9.         Memory Management in FF ___________________ 27

        10.         The File System and Handles _______________ 28

        11.         Rebuilding the System _____________________ 28

        12.         FF and Batch Files ________________________ 29

        13.         Extra stuff included with FF ______________ 30

        14.         Forth History: how did we get here? _______ 30




















 Overview        FF, What is it all about?

          The first thing you should know is that FF is trying to
        achieve a number of conflicting goals.  With FF I am trying
        to provide a Forth system that provides all of the following:

                A system that is familiar to the large
                installed base F83 users.

                A system that brings Forth fully into the
                realm of files.

                A Forth system that is as unstrange as
                possible to C and Pascal programmers.

                A system which maintains Forths interactive
                nature.

                A system which if FAST to compile and run.

                A FAT system with many tools, which still
                has room for an application program.

          Impossible, you say. Perhaps, but I think if you give FF a
        chance you may find some things you like.

          In line with the above goals, here is a list of some of
        FF's major features.

                Direct threaded dictionary for speed.

                Seperated lists & heads to increase space.

                Prefix assembler to enhance readability.

                Assembler supports both Prefix as well as
                Postfix assembly syntax for familiarity.

                Full DOS access from system and COMMAND
                level control.

                Full Handle/Path based file system.

                View works across directory boundries.

                Full user configurable sequential text
                editor provided in source.

                Full DOS memory managment interface.

          Much more of course is provided, but enough of this
        editorializing. Let's get started.



 1. Getting Started

          FF is a Forth system whose origins can be traced back to
        F83. FF has been tailored to use sequential files for source,
        and all references to BLOCK have been removed. While this may
        seem very strange at first, allow me a few minutes, and you
        will, I believe, find FF to be more familiar than you might
        expect.

        Installing FF

          FF is provided on a single floppy disk, which you have
        already copied FF onto your hard disk and expanded or you
        wouldn't be reading this.  To install FF, you will need only
        type the name of the batch file which will set the paths of
        some of the files to be loaded to your current directory
        structure.

                Type:   INSTALL <enter>

          If you don't have a batch file called INSTALL.BAT, then you
        can type the command manually as follows:

                Type:   PKERNEL - SEQINIT FLOAD FF.SEQ <enter>

          Either of the above will re-compile FF from the PKERNEL
        file, configuring FF for your directory structure in the
        process.

          You will probably want to read the screen while the install
        is taking place, as several interesting messages are
        displayed while the installation occurs.

        Starting FF

          Once FF has been installed on your computer, you can start
        it up by typing "FF <enter>" from the keyboard.  This will
        display a signon message about the version number, available
        memory, authors, etc.

        Opening a file:

          Type the following:   OPEN BANNER <enter>

          The file BANNER.SEQ will be opened.  We can load it with:

                                1 LOAD <enter>

          This prints a nice demo message.  This demo came from the
        F83X system.

          We can edit the source for BANNER by typing:

                                ED <enter>

          You will now be in the editor, viewing the first 20 lines
        or so of BANNER.SEQ.  You can page down through the file with
        the PgDn key on the keypad, and back up with the PgUp key.
        For now, page down to the bottom of the file with PgDn, and
        there you see the definition of the word DEMO, which prints
        out our demonstration banner.

          Now let's create a new file and put a new DEMO definition
        with our own banner message in it.  Leave the editor by
        typing Shift-ESC twice, that is, hold down the Shift key and
        press the ESC key two times.  You will now be back in Forth
        without saving any changes you may have accidently made to
        BANNER.SEQ.

          To create the new file, type the following:

                SED MYBANNER <enter>

          FF will start the editor, and try to open the file
        MYBANNER.  If it is present, FF will open it.  If it is not,
        then FF will automatically create a new file called
        MYBANNER.SEQ and place you in the editor in that file,
        prepared to enter text.

          Type in the following definition, using the <enter> key to
        add new lines to the file as needed.  The arrow keys can be
        used to move around, but you will not be allowed to move
        below the line containing the little up pointing triangle at
        the left edge of the screen, as this represents the end of
        the current file.

        : MYBANNER      ( --- )
                        " HELLO" BANNER
                        " FROM" BANNER
                        " YOURNAME" BANNER ;

          Note that YOURNAME must be no longer than 11 characters.

          Now that you have typed in or edited the above definition
        into the file BANNER.SEQ, leave the editor saving the text
        you have entered, by pressing ESC twice.  DON'T use Shift
        this time, as we REALLY want to save the program.

          Let's compile the program.  Type:

                        FLOAD MYBANNER <enter>

          The file MYBANNER.SEQ is opened, and loaded.  If you
        entered the program as shown, then all should be well, and
        Forth should come back with the "ok" message.  You could have
        compiled the program by typing 1 LOAD <enter>, since the file
        was already open.



          Now that MYBANNER is compiled, type its name to make it do
        it's stuff:

                        MYBANNER <enter>

          You should have seen your name scroll up on the screen, if
        you didn't, try editing the source file and correcting your
        typing error.

          At this point, you can VIEW the source for MYBANNER by
        typing:
                        VIEW MYBANNER <enter>

          FF will locate the source for your MYBANNER word, and
        display the source file starting at the line where MYBANNER
        was started.  A shorter word for VIEW called LL (Locate &
        List) is provided to save typing.

          Now let's look at some Forth words with LL, and some of the
        other file traversal words.  Type:

                        LL DUP <enter>

          The source for DUP will be displayed, with the line where
        the definition of DUP starts underlined.  Above the line
        where DUP starts is the reverse video message showing the
        filename of the source for DUP. Now type:

                        N <enter>

          The screen will blink and display group of lines starting
        16 lines farther into the KERNEL1.SEQ source file.  With the
        "N" word, you can scan quickly through a sequential file.
        The inverse of "N" is "B".  If you type it followed by
        <enter>, the previous 16 lines will be displayed.  Another
        display word "L" is provided to redisplay the current
        location in the file again.


          One last word you will find VERY useful is WORDS.  It is
        used as follows:

                        WORDS HE <enter>

          The above command sequence will display all words in all
        vocabularies of Forth that contain the letter sequence "HE".
        This is very useful when you don't know how to spell the word
        you are looking for, but you know it contains a particular
        character sequence.  WORDS by it self will show all words in
        the current vocabulary only, and the special sequence "*.*"
        following WORDS is recognized as a command to display all
        words of all vocabularies.



                Here is a list of the words we have covered.

        OPEN <filename> <enter>         Opens filename.

        1 LOAD <enter>                  Compiles the open file.

        ED <enter>                      Starts editing the current
                                        file.

        SED <filename> <enter>          Specifies a file to edit.

        FLOAD <filename> <enter>        Loads filename.

        HELP <enter>                    Displays a help screen.
        HELP <forth_word> <enter>       Shows the source for a
        VIEW <forth_word> <enter>       Forth word.
        LL <forth_word> <enter>

        N <enter>                       Shows next 16 lines.

        B <enter>                       Shows previous 16 lines.

        L <enter>                       Re-display current 16 lines.

        WORDS <sub_string> <enter>      Display all words containing
                                        <sub_string> in all vocabularies.

        SEE <word>                      Decompile the memory copy of
                                        the word, and show the source.


























 2. Sequential File Forth:  An Overview

        More than 90% of what is in FF came from F83, much of
        what you are seeing, should be somewhat familiar.  Things
        that are different, are normally different because they need
        to be.  There are a significant number of things about F83
        that I would have liked to change, but did not for
        compatibility reasons.  However since BLOCK is not present,
        you will experience a period of difficulty.  I hope you will
        take some solace in knowing I have at least tried to make the
        transition as painless as possible.  Many of the familiar
        file manipulation words from F83 are still present, and those
        that are will work in a very similar if not identical way.
        Some of these are:


        OPEN, CLOSE, VIEW, OK, L, N, B, ED, LOAD, LIST, EDIT


          Some words like BLOCK, and BUFFER, simply could not be fit
        into the new scheme of things in a logical manner, and so
        were omitted.  To load an entire file, use the sequence FLOAD
        <filename>.  Listing through a file is best done with VIEW,
        although of course the file will have already had to be
        loaded. To LIST through a file which has not been loaded, you
        can use LIST, which lists from a line number, rather than
        from a block, but the following sequence is easier.


                OPEN <filename> <enter> opens file
                L <enter>               lists first 18 lines
                N <enter>               lists next group of lines.
                B <enter>               list previous group of lines.


          These words are very fast using indices into the file to
        maintain their line pointer information.

          the word LOAD still exists, but loads the rest of a file
        starting at the line number specified.

          The compiler in FF has been tailored to be as fast as I
        could make it.  Since much of the functionality of WORD has
        been moved into CODE for performance, this system compiles
        sequential text files much faster than standard F83 compiles
        BLOCKs.

          The debugger has been enhanced to allow nesting and
        un-nesting of ":" definitions for more capable debugging.






          The editor is WordStar compatible from a cursor control key
        stand point, with the keypad functions fully supported,
        along with some function keys.  Full search, replace, and
        global replace are provided, along with copy and paste of
        text segments within a file as well as between files.  The
        editor can be used to directly convert existing BLOCK files
        smaller than 64k to sequential files.  See the section on the
        editor for detailed information.

          A utility is provided to convert even very large BLOCK
        files into sequential files.  The resulting savings in mass
        storage is typically greater than 60%.

          The source for FF is, of course, provided.  You can tailor
        it to your way of doing things if you don't like mine.


 3.  What is the same as F83?

          From a low-level Forth standpoint, FF is very similar to
        F83.

          Multi-tasking is unchanged.

          The assembler in POSTFIX mode is fully compatible with the
        F83 assembler.

          VIEW, FIX, L, N, B, ED, LISTING, and OK work as they did
        in F83.

          LOAD and LIST need a line number rather than a screen
        number.

          \S is available, and stops compilation of the remaining
        portion of the current file.

          DBG and DEBUG work as they did in F83, with more
        functionality added.  A decompiled source of the current
        definition being debugged is displayed at the top of the
        screen.

          SEE is available, but has been enhanced to display the
        conditional structures in nested source form, for much
        increased readability.

          WORDS works as it did in F83, with the enhancement that you
        can specify a text string following it to display a subset
        of words in the dictionary that contain the substring. WORDS
        *.* will display all words in all vocabularies.






 4.  What is different from F83?

          The system is now Direct threaded CODE. This results in
        the CODE fields of Colon definitions being 3 bytes instead
        of 2. Approximately a 15% increase in performance results.

          The LIST portion of all ":" definitions has been moved to
        another segment. This resulted in at least a doubling of the
        program space available. A small loss of performance
        resulted. (about 10%)

          System based time and date functions have been added, for
        measurement as well as display of the time and date.  The
        word TIMER will allow measuring the performance of various
        operations in FF.

          Very fast screen I/O is provided for editor and normal text
        display.  The words FAST and SLOW switch between direct
        screen I/O and BDOS function I/O.

          Screen hi-lighting for a monochrome display is supported
        for underline, bold, reverse, bold blink, and reverse blink.

          Paths are fully supported, as entered from the command
        line, or applied to a file automatically if not specified.

          Many DOS command line functions are built-in, like DIR,
        COPY, FORMAT, DEL, REN, MD, RD, CHDIR, PATH, and more may be
        added at a cost of about 40 bytes each.

          Cursor shape control is provided, in the form CURSOR-ON,
        CURSOR-OFF, NORM-CURSOR, MED-CURSOR, BIG-CURSOR, GET-CURSOR,
        and SET-CURSOR.

          BLOCK, BUFFER, B/BUF, C/L, L/SCR, BLK, FCB, and no longer
        exist.

          The word COPY, is now a DOS function to copy files.

          Environment access is supported, see the ENVIRON.SEQ file.















 5.  Differences from PF, ZF & DF


          This Forth was implemented by Tom Zimmer, with substatial
        help from Robert L. Smith. All of the Direct Threaded low
        level code modifications came from Bob's LaForth
        implementation.

          This is yet another step in the Forth evolution being
        undertaken to obtain the ideal Forth system. This Forth
        maintains very high compatibility with ZF & DF which was it's
        predecessor. The primary problem that you are likely to
        encounter, is that CODE fields are three (3) bytes rather
        than 2, and the CODE field of a CODE word does not point to
        code, but contains code.

          FF has moved ":" LISTs to a seperate segment, so there are
        two bytes in the BODY of each ":" definition that points into
        LIST space the the ":" definitions LIST of CFAs.  LIST space
        is accessed with X words, like X@ and X!. The word XPERFORM
        has been added for performing a word in LIST space.

          VARIABLEs, CONSTANTs, and strings are handles in the same
        way as PF, that is they are in CODE space. This segmentation
        seems to provide a reasonable balance. As the dictionary
        expands, more user data space is needed, which works well with
        FF, as most of the free space is in CODE/DATA space.

          This system will full circle meta compile and extend, with
        the provided batch files for simplicity.

          As FF currently exists, there is about 30k of LIST
        dictionary space, and 40k of CODE space. which can be expanded
        by removing some of the optional files from the list of load
        files in FF.SEQ. The removable files are marked. Some of these
        files are listed as follows:

        PATHSET.SEQ     WORDS.SEQ       COLOR.SEQ       DUMP.SEQ
        DECOM.SEQ       DEBUG.SEQ       STATUS.SEQ      MACROS.SEQ
        PATCHER.SEQ     FILSTAT.SEQ     FWORDS.SEQ

          If some of these files are removed, a significant savings in
        dictionary space will result.

          A tool of the type used in F83X has been added, called
        ?NEEDS. This word when followed by a filename will
        conditionally load the specified file if the file has not
        already been loaded. Be sure to include the filename
        extension. Another word ?UNWANTED, when followed by a
        filename, aborts with an error if the Unwanted file has
        already been loaded.




 6.  SED the Editor

          For full information on the editor in FF, please see the
        file SED.TXT


 7.  The Debugger, and the Tools Available


        THE DEBUGGER

          The debugger is very similar to the F83 debugger.  Some
        features have been added to enhance its operation.  The
        decompiled source for the current definition being debugged
        is displayed while debugging. A typical command sequence
        might be as follows:

                DEBUG WORDS <enter>     specify WORDS to be debugged
                                        as soon as it is executed.
                        or

                DBG WORDS <enter>       debug WORDS right now.

          Once in the debugger, you will be shown a display similar
        to the following:

                17469   INWFLG          ?>  _

          At this point, pressing return will cause the word INWFLG
        to be executed, and the debugger will print the stack after
        execution, and step to the next word in the list and wait for
        a command.  Notice the fields in the above example.  The
        number on the left is the address in memory where the
        debugger is currently working.  The next word INWFLG is the
        word the debugger is about to execute.  The next symbol "?>"
        is a marker pointing to what will be the printed stack
        contents after we press <enter>.  The question mark symbol is
        the command we must press to see the command list for the
        debugger.  If we press that now, we will see:

                C-cont, F-forth, Q-quit, N-nest, U-unnest:

          These are the commands you can use in the debugger.  Their
        functions are as follows:

        C-cont          Trace continuously until a key is pressed.

        F-forth         Allow entry of Forth command lines until
                        <enter> is pressed on an empty line.

        Q-quit          Quit the debugger, and unpatch next.




        N-nest          Nest into the ":" definition we were about
                        to execute.  Only works on ":" definitions,
                        and deferred words.

        U-unnest        Unnest the current ":" definition being
                        debugged.  Re-enters the debugger on the next
                        higher level.


        DEBUGGING with SOURCE displayed

          You will have noticed that the upper portion of the screen
        is filled with the source for the word you are currently
        debugging.  This is to make it easier to follow the debug
        process. You may want to turn off the source display, if it
        interferes with your the debuging process. The words to
        control this are:

                SRCOFF          turn off the source display
                SRCON           turn on the source display

          The default state is ON.


        CONSTANTS as VARIABLES and what to do with them

          A set of operators has been included for manipulating
        constants.  Since constants are faster at run time than
        variables, performance critical operations can take advantage
        of these.  They may also provide a somewhat more readable
        source.  Here is a list of them:

                =:              \ value =: constant-name
                !>              \ value !> constant-name
                                \ assign value into constant-name

                @>              \ @> constant-name ( --- n1 )
                                \ returns contants of its BODY.

                +!>             \ value +!> constant-name
                                \ increment constant-name by value

                incr>           \ incr> constant-name
                                \ increment constant-name by one

                decr>           \ decr> constant-name
                                \ decrement constant-name by one

          These operators are written in assembly, so they will be
        very fast.





        SEEing into Forth definitions

          FF provides the standard F83 decompiler, called SEE.  SEE
        has been modified to display a decompiled source that is in
        most cases the very similar to the source on disk.

        TIMER and measurement of execution time

          A complete set of time and date manipulation words has been
        provided, here is an explanation of their usage:

                TIMER           ( words --- )

          TIMER performs the Forth words following on the same
        command line, and when they finish execution, TIMER prints
        the elapsed time required for their execution.

                TIME-RESET      ( --- )

          Reset the accumulated time value in the double variable
        STIME to zero, in effect resetting the current elapsed time
        to zero.  This word is used at the beginning of a sequence of
        operations you want to time.  The word .ELAPSED is used at
        the end of the operations to print the elapsed time since the
        last TIME-RESET.

                .ELAPSED        ( --- )

          Print the elapsed time since the last TIME-RESET was
        performed.

                TENTHS          ( tenths_ofa_second --- )
                SECONDS         ( seconds --- )
                MINUTES         ( minutes --- )
                HOURS           ( hours --- )

          Time delay words use the system time function to obtain
        very accurate time delays.  Background processing continues,
        as pause is called in the wait loop.  Another deferred word,
        PAUSE-FUNC, is also in the loop, which can be re deferred to
        perform any function you want done while the delay is
        occurring.

        DATE Control Words

          FF provides several words for getting and setting the date
        and time as follows:

                GETDATE         ( --- d1 )

          Return d1 the 32bit binary date from the operating system.




                SETDATE         ( d1 --- )

          Given the binary date d1, set the system clock to that
        date.

                GETTIME         ( --- d1 )

          Return d1 the 32bit binary time from the operating system.

                SETTIME         ( d1 --- )

          Given the binary time d1, set the system clock to that
        time.

                .DATE           ( --- )

          Print to the screen, the current date, in the format
        MM/DD/YY, where MM is month, DD is day, and YY is year.

                .TIME           ( --- )

          Print to the screen, the current time, in the format
        HH:MM:SS.HR, where HH is hours, MM is minutes, ss is seconds,
        and HR is hundredths of a second.

        Multiple line COMMENT words in FF

                COMMENT:        ( lines_of_text --- )

          Starts a group of lines that are to be treated as comments,
        until a terminating "COMMENT;" is found.

                .COMMENT:        ( lines_of_text --- )

          Starts a group of lines, that are to be printed to the
        terminal, until a terminating "COMMENT;" is found.

        SCREEN control words in FF

                FAST            ( --- )

          Select the Fast screen output routines that are very
        hardware dependant.  Much faster than BDOS, but requires VERY
        compatible hardware.

                SLOW            ( --- )

          Select the SLOW screen output routines, these routines use
        BDOS for screen output, and are less hardware dependant than
        FAST.





                >UL             ( --- )         underline
                >REV            ( --- )         reverse
                >BOLD           ( --- )         bold
                >BOLDUL         ( --- )         bold underline
                >BOLDBLNK       ( --- )         bold blink
                >REVBLNK        ( --- )         reverse blink
                >NORM           ( --- )         normal video

          Select the various types of attributes available on the
        monochrome monitor.



          COLOR support has been added.  FF as delivered is
        configured for Monochrome, but will work on a color monitor.
        The INSTALL process will automatically install color support
        if a color board is being used during installation.

                >FG             ( n1 --- )      foreground
                >BG             ( n1 --- )      background

          Words from the COLOR.SEQ file that allow setting the
        foreground and background colors on a color monitor:

                >ATTRIB1        ( --- )
                >ATTRIB2        ( --- )
                >ATTRIB3        ( --- )
                >ATTRIB4        ( --- )

          Deferred words to allow selection of the various display
        attributes for the current display board.  They default to
        the following attributes for Monochrome and Color.


                                MONOCHROME          COLOR
                  word                          bgrnd   fgrnd
                ---------------------------------------------
                >ATTRIB1        UNDERLINE       BLUE    GREEN
                >ATTRIB2        BOLD UNDERLINE  RED     WHITE
                >ATTRIB3        BOLD            BLUE    WHITE
                >ATTRIB4        REVERSE         RED     WHITE

          These values can be changed by changing either COLOR.SEQ,
        or MONOCROM.SEQ and re-installing the system with INSTALL.BAT.


                SAVESCR         ( --- )         save screen
                RESTSCR         ( --- )         restore screen

          These words give you the ability to save the screen
        contents and later restore the screen to its original
        appearance in a simple way. SAVESCR may be used and nested
        up to three times before RESTSCR needs to be done. That is,
        three screens can be saved and sequentially restored.

        COMPILATION control words

                OK <enter>

          Compile the currently open file, starting at the beginning,
        and continuing through the end of the file or until an error
        is encountered.

                <line_number> LOAD <enter>

          Start loading the current file starting at the
        <line_number> specified.  Loads through the end of the file
        or until an error is encountered.


        PRINTING Source files in FF.

          Files can of course be printed while in the editor, but you
        can also print files from the Forth command line as follows:

                OPEN <filename> <enter>         open a file
                LISTING <enter>                 print the file

          The print format is the same as the default format for the
        editor.  Another command which combines the two commands
        above is as follows:

                FPRINT <filespec> <enter>       open and print

          Literally opens the file and performs a LISTING. The source
        for the word FPRINT is available in the file FWORDS.SEQ


        CONDITIONAL COMPILATION

          The word #IF has been added, which accepts a boolean flag,
        and determines if the lines following #IF are loaded up until
        the #ENDIF. A TRUE flag causes the lines to be loaded. A
        FALSE flag causes the lines to be skipped.

                TRUE #IF

                        .( This message will be printed.)

                #ENDIF










        MACROS in FF, and SED

          A file called MACROS.SEQ is provided, which implements
        keyboard macros in Forth, at the level of KEY.  These macros
        can therefore be used in the editor also.  The macros are
        used as follows: (the sequence "Alt-M" means hold down the
        "Alternate" key and press the "M" key.)

                Alt-M           start defining a macro.
                Alt-1           we are defining the Alt-1 macro.

                Enter any keys you want in the macro, up to 128 keys.

                Alt-M           completes the definition of the Alt-1
                                macro.

          Any keys typeable on the keyboard except Alt-m, and Alt-1
        to Alt-5 can be included within a macro.

          To execute a macro, simply type its key name:

                Alt-1           executes the macro key sequence for
                                the Alt-1 key.

          Currently macros may be only 127 characters in length,
        although this can be changed by modifying the MAXMAC constant
        and recompiling the system.




























 8.  DOS: the interface

          The interface to DOS occurs at several levels.  In this
        section we will discuss the interface to the DOS commands as
        opposed to the DOS system calls.

          It is convenient to be able to issue DOS commands from
        within FF.  This avoids having to leave FF to do the normal
        housekeeping things that are regular occurrences in a DOS
        based computer.  In line with this, FF implements a pair of
        commands:


                $SYS    ( a1 --- f1 )
                SYS     ( text --- )


          These words allow performing almost any DOS command line
        operation you would want to do.  To make things even more
        convenient, several additional words have been coded which
        use the $SYS word for specific functions.  They are as
        follows:


          DIR  FORMAT  FTYPE  DEL  CHDIR  COPY  REN  RD  MD  PATH

          A:    B:     C:


          These commands may be used as they are in DOS.  The word
        FTYPE replaces the DOS word TYPE for obvious reasons.

          If you press Control-C, or Control-Break during the
        execution of any of the above words, operation will abort
        back to Forth.

                ` <command> <enter>

          BACKTICK followed by one space and a DOS command sequence
        performs the DOS command sequence and returns to Forth.















 9.  Memory Management in FF

                FF uses memory as follows:

                |---------------------| ?CS:
         ^      |                     |
         |      |       Forth         |
         |      |       Kernel        |
         |      |                     |
         |      |---------------------|
         |      |       System        |
         |      |     Extensions      |
         |      |---------------------| HERE, DP @
         |      |     Dictionary      | PAD, DP + 80
         |      |     Free space      |
        64k     |         |           |
       bytes    |         v           |
         |      |         ^           |
         |      |         |           |
         |      |     Data stack      |
         |      |---------------------| SP0 @
         |      |        TIB          | TIB, 'TIB @
         |      |         |           |
         |      |         v           |
         |      |         ^           |
         |      |         |           |
         v      |    Return stack     |
                |---------------------| RP0  @, End code space.

                |---------------------| YSEG @, Start head space.
         ^      |       hash table    |
         |      |---------------------|
         |      |                     |
        32k     |       headers       |
       bytes    |                     |
         |      |---------------------| YHERE,  YDP @
         |      |       header        |
         v      |     free space      | YHERE + 32767
                |---------------------|

                |---------------------| TSEGB, TSEGE
         ^      |                     |
     64k bytes  |     Edit Buffer     |
         v      |                     |
                |---------------------| LSEG
                |  Line pointer list  |
                |---------------------| DSEG
                |  Lines deleted buf  |
                |---------------------| RSEG
                | Restore display buf |
                |---------------------|




        COLON ":" Data Structure

          Here is the data structure used for a colon definition in
        FF.

        The COLON ":" definition of the word HEX.

                                     ----------------
            HEAD SPACE               [ VIEW offset  ] VIEW
                                     [ LINK pointer ] LINK
                                     [      83 hex  ] NAME
                                     [   H          ]
                                     [   E          ]
                                     [   X + 80 hex ]
                Points to CODE space [ CFA pointer  ] --------v
                                     ----------------         |
                                                              |
                                     ----------------         |
            CODE SPACE               [     CALL     ] CFA <---<
                                     [     NEST     ]
                Points to LIST space [ LIST POINTER ] BODY >--v
                                     ----------------         |
                                                              |
                                     ----------------         |
            LIST SPACE               [ cfa of (LIT) ] LIST <--<
                                     [     16       ]
                                     [ cfa of BASE  ]
                                     [ cfa of   !   ]
                                     [ cfa of UNNEST]
                                     ----------------




10.  The File System and Handles

          For full information on the file system as used in FF,
        please see the file FILES.TXT

















11.  Rebuilding the System.


          If you need to change a parameter or function in the FF
        system, you will need to re-compile FF and/or PKERNEL.  This
        is simply done with the provided batch files as follows:


                C> PMETA <enter>        re-compiles PKERNEL.COM
                C> INSTALL <enter>      re-extends to create FF.COM


          Either of these may be performed from the keyboard while in
        DOS.

                TURNKEY

          The word TURNKEY and some associated words are included in
        the file SAVESYS.SEQ. TURNKEY is used as follows:

                ' MYAPPL TURNKEY MYAPP.COM <enter>

          After completing an application compile, the word MYAPPL
        is defined to be performed by the program name MYAPP.COM.
        TUNRKEY automatically sets up the proper memory managment to
        allocate 64k for your program, but does not save the HEADS.
        Minimum initialization is performed. A file specified on the
        command line will be opened, and you can use BL WORD to pick
        up additional parameters from the command line. You will NOT
        of course be able to interpret, since heads are not saved,
        and you applicaton will need to handle all errors and return
        to DOS when the program completes.

        BUILDING an APPLICATION

          Before attempting to build an application, you will need to
        make a copy of FF.SEQ, for customization. Many of the later
        files in FF.SEQ are utilities, and will not be needed in your
        application. Start by writing your program and compiling it
        on FF.EXE. Work in this environment until you are sure your
        program works. Now insert your program filename into the copy
        of FF.SEQ you made, about half way down, and try to compile
        the copy of FF.SEQ. If it compiles then you can move your
        application file lower, until you have determined what
        utilities are needed by your application. Strip out all files
        above your application file, and load the file SAVESYS.SEQ.
        Use TURNKEY as previously described to make an executable
        .COM file.







12.  FF and Batch Files.


          FF allow commands to be passed to Forth on the DOS command
        line in the following manner:

                C> FF <filename> <forth words> <enter>

          This example illustrates how you can start FF with a
        specified file name, and perform commands on the file.  An
        example of how this might be used is as follows:

                C> FF BANNER OK <enter>

          Here we are starting FF with the file BANNER.SEQ, and then
        performing OK to compile the file.  Another way to use
        command line parameters is:

                C> FF - <forth words> <enter>

          Here we are starting FF, followed by a dash "-" to tell FF
        we are not opening a file, then telling FF to perform the
        Forth words following the "-".  Here is an example:

                C> FF - FIX DIR <enter>

          This example starts up FF without a file and tells FF we
        want to fix the word DIR.  It will locate the word DIR and
        start up the editor with the cursor located on the first
        line of the DIR definition.

          You can get to batch files now, as you can see many types
        of commands could be given to FF on the command line.  Here
        are the contents of the PMETA.BAT:

                FF - FLOAD META86

          This single line batch file re-meta-compiles the FF kernel
        file and re-creates the PKERNEL.COM file.  A similar batch
        file is provided to extend the system.

          The one caution on batch files is you must not place
        commands on the command line which cause the command line to
        be interpreted again.  The words HELLO and COLD are such
        words, and should not be used on the command line of FF.COM,
        or PKERNEL.









13.  Extra stuff included with FF

          See the separate file ZIMMER.TXT, CURLEY.TXT and SMITH.TXT
        for information on the extras provided with each archive
        file.

14.  Forth History, how did we get here?

          This Forth system started out as an experiment to see if a
        development environment could be created that would be as
        interactive as a BLOCK Forth system, with as many of the same
        tools as possible.

          Over the past several years, I have observed the
        Programming community for other languages.  Several years
        ago, Forth had enormous advantages over Fortran, Pascal, and
        C in terms of development interactivity.  The Forth
        development cycle was very short, and new code modules could
        be put together for experimentation very quickly.  As the
        years went by, the Programmers for these other languages
        began to realize there had to be something better than their
        traditional compile debug cycle, i.e.

          ----> Enter the editor from operating system.
          | |   Make changes with LINE editor.
          | |   Leave editor back to operating system.
          | |   Start Compiler on source module.
          | |   WAIT A LONG TIME FOR THE COMPILER.....
          | |   Discover an error.
          | |
          | --< LOOP back up until all compile errors are found.
          |
          |     Now start Linker on all modules.
          |     WAIT A LONG TIME FOR THE LINKER.....
          |     Discover Link error.
          ----< Go back to beginning and try again.

          The above loop could be measured in DAYS, and was normally
        at least 30 minutes long.

          Forth did away with much of the above.  The editor was
        integrated into the Forth/Operating system environment, so
        the time to start up or leave the editor was zero.  The
        compiler was incremental, so programs could be debugged a
        piece at a time, and there was no linker at all.  This
        naturally resulted in a productivity improvement and a
        significant reduction in programmer frustration.

          As the years went by, other programmers noticed how much
        easier BASIC was to use than other compiled languages, since
        it had a built in editor, and didn't have to compile at all.
        Of course it was SO SLOW.., but then along came TURBO PASCAL.
        It created fast compiled code, had an integrated SCREEN
        editor, and compiled like BLAZES.

          We now start to see some similarities to Forth, a much
        superior development environment, where the development
        iteration cycle has been reduced to a very small number.  But
        Turbo Pascal still lacked Forth interactivity, and ability to
        incrementally debug programs as they are developed.

          Finally along came the Macintosh (Those who know me knew I
        would figure out a way to mention it), and Light Speed
        Pascal.  It had evolved from Mac Pascal, an interactive and
        pseudo interpreted Pascal for the Mac.  LSP (Light Speed
        Pascal) had Windows, a Built in Screen editor, Compiled
        modules, a Very fast compiler and a Light Speed Linker, with
        the ability to test small segments of code, and two built-in
        debuggers: one for Pascal, and one for Assembly.  I bought it
        and liked the environment very much.  The only problem was
        that is was PASCAL not Forth.  I did, however, like the
        advantages of sequential files.  Here is a partial list:

                Source files are smaller, so backing or
                transporting file is easier.

                Sequential source files can be manipulated
                or viewed by programs that other people
                have, not just by the forth block editor.

                There is no artificial limitation placed on
                definition size.  In the block based system
                I was always giving up line zero for a
                comment line, and line 15 for nudge space.

                There is no artificial limit placed on the
                amount of comments I can place with the
                source.  Again, compared to blocks with
                shadows, 16 lines of shadows was either too
                much or too little.

                Sequential files provide a much more
                natural interface to the operating system.

                I love being able to insert room for a new
                definition in the middle of a source file,
                without having to drop out of the editor,
                and use MORE and CONVEY to move things
                around, all I have to do is press <enter>.


          Hmm.  I wonder what Forth would be like with Sequential
        files?  Well, it has arrived.







          So here we are at the end (or beginning) of a long road,
        looking back at what we have done, and looking forward to
        the future.  Blocks were certainly very useful for forcing me
        to modularize my code.  That was a big advantage while I was
        learning Forth.  Maybe newcomers to Forth should be required
        to learn the system on a BLOCK version, but now that I have
        come of age, I think I know where to modularize my code
        better than the computer.

        Thoughts on BLOCK

          One last thought.  Although all references to block
        operations have been removed from FF, that does not mean you
        cannot use block type disk operations in your programs.  Here
        is the equivalent FF source for some simple block read and
        block write functions:

                create blockbuf 1024 allot

                : BLKREAD   ( n1 --- a1 )
                            1024 um* seek
                            blockbuf dup 1024 shndl @ hread drop ;

                : BLKWRITE  ( n1 --- )
                            1024 um* seek
                            blockbuf 1024 shndl @ hwrite drop ;

          These definitions will read and write a block of data from
        the current file.  While it is true that the above does not
        provide anything like a complete Forth BLOCKs functionality,
        like no auto write on update, and no virtual buffering, it
        does show how simple it is to access random records in a
        block.

          Now I hope I have provided some insight into the logic
        behind the development of FF without BLOCKs.  I hope you can
        find a use for it as I have.

                                        Tom Zimmer